JavaScript Asynkron Kontekstpropagering: Anmodningssporing og Fortsættelse med AsyncLocalStorage

I moderne server-side JavaScript-udvikling, især med Node.js, er asynkrone operationer allestedsnærværende. At håndtere tilstand og kontekst over disse asynkrone grænser kan være en udfordring. Dette blogindlæg udforsker konceptet asynkron kontekstpropagering med fokus på, hvordan man bruger AsyncLocalStorage til effektivt at opnå anmodningssporing og fortsættelse. Vi vil undersøge fordelene, begrænsningerne og anvendelser i den virkelige verden og give praktiske eksempler for at illustrere brugen.

Forståelse af Asynkron Kontekstpropagering

Asynkron kontekstpropagering refererer til evnen til at vedligeholde og propagere kontekstinformation (f.eks. request-ID'er, brugergodkendelsesoplysninger, korrelations-ID'er) på tværs af asynkrone operationer. Uden korrekt kontekstpropagering bliver det svært at spore anmodninger, korrelere logs og diagnosticere ydeevneproblemer i distribuerede systemer.

Traditionelle tilgange til håndtering af kontekst er ofte afhængige af eksplicit at videregive kontekstobjekter gennem funktionskald, hvilket kan føre til omstændelig og fejlbehæftet kode. AsyncLocalStorage tilbyder en mere elegant løsning ved at give en måde at gemme og hente kontekstdata inden for en enkelt eksekveringskontekst, selv på tværs af asynkrone operationer.

Introduktion til AsyncLocalStorage

AsyncLocalStorage er et indbygget Node.js-modul (tilgængeligt siden Node.js v14.5.0), der giver en måde at gemme data, der er lokale for en asynkron operations levetid. Det skaber i bund og grund et lagerplads, der bevares på tværs af await-kald, promises og andre asynkrone grænser. Dette giver udviklere mulighed for at tilgå og ændre kontekstdata uden eksplicit at skulle videregive dem.

Nøglefunktioner i AsyncLocalStorage:

• Automatisk Kontekstpropagering: Værdier gemt i AsyncLocalStorage propageres automatisk på tværs af asynkrone operationer inden for den samme eksekveringskontekst.
• Forenklet Kode: Reducerer behovet for eksplicit at videregive kontekstobjekter gennem funktionskald.
• Forbedret Observerbarhed: Faciliterer anmodningssporing og korrelation af logs og metrikker.
• Trådsikkerhed: Giver trådsikker adgang til kontekstdata inden for den nuværende eksekveringskontekst.

Anvendelsestilfælde for AsyncLocalStorage

AsyncLocalStorage er værdifuld i forskellige scenarier, herunder:

• Anmodningssporing: Tildeling af et unikt ID til hver indkommende anmodning og propagering af det gennem hele anmodningens livscyklus til sporingsformål.
• Autentificering og Autorisation: Opbevaring af brugergodkendelsesoplysninger (f.eks. bruger-ID, roller, tilladelser) for adgang til beskyttede ressourcer.
• Logning og Revision: Tilknytning af anmodningsspecifik metadata til logbeskeder for bedre debugging og revision.
• Ydeevneovervågning: Sporing af eksekveringstiden for forskellige komponenter inden for en anmodning til ydeevneanalyse.
• Transaktionshåndtering: Håndtering af transaktionstilstand på tværs af flere asynkrone operationer (f.eks. databasetransaktioner).

Praktisk Eksempel: Anmodningssporing med AsyncLocalStorage

Lad os illustrere, hvordan man bruger AsyncLocalStorage til anmodningssporing i en simpel Node.js-applikation. Vi opretter en middleware, der tildeler et unikt ID til hver indkommende anmodning og gør det tilgængeligt gennem hele anmodningens livscyklus.

Kodeeksempel

Først, installer de nødvendige pakker (hvis nødvendigt):

            npm install uuid express
            

              
                Copy
              
            
          

Her er koden:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware til at tildele et request-ID og gemme det i AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simuler en asynkron operation
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Route-handler
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

I dette eksempel:

1. Vi opretter en AsyncLocalStorage-instans.
2. Vi definerer en middleware, der tildeler et unikt ID til hver indkommende anmodning ved hjælp af uuid-biblioteket.
3. Vi bruger asyncLocalStorage.run() til at eksekvere anmodningshandleren inden for konteksten af AsyncLocalStorage. Dette sikrer, at alle værdier, der er gemt i AsyncLocalStorage, er tilgængelige gennem hele anmodningens livscyklus.
4. Inden i middlewaren gemmer vi request-ID'et i AsyncLocalStorage ved hjælp af asyncLocalStorage.getStore().set('requestId', requestId).
5. Vi definerer en asynkron funktion doSomethingAsync(), der simulerer en asynkron operation og henter request-ID'et fra AsyncLocalStorage.
6. I route-handleren henter vi request-ID'et fra AsyncLocalStorage og inkluderer det i svaret.

Når du kører denne applikation og sender en anmodning til http://localhost:3000, vil du se request-ID'et logget i både route-handleren og den asynkrone funktion, hvilket demonstrerer, at konteksten propageres korrekt.

Forklaring

• AsyncLocalStorage-instans: Vi opretter en instans af AsyncLocalStorage, som vil indeholde vores kontekstdata.
• Middleware: Middlewaren opsnapper hver indkommende anmodning. Den genererer et UUID og bruger derefter asyncLocalStorage.run til at eksekvere resten af anmodningshåndteringspipelinen *inden for* konteksten af dette lager. Dette er afgørende; det sikrer, at alt nedstrøms har adgang til de gemte data.
• asyncLocalStorage.run(new Map(), ...): Denne metode tager to argumenter: et nyt, tomt Map (du kan bruge andre datastrukturer, hvis det passer til din kontekst) og en callback-funktion. Callback-funktionen indeholder den kode, der skal eksekveres inden for den asynkrone kontekst. Enhver asynkron operation, der startes inden for denne callback, vil automatisk arve de data, der er gemt i Map'et.
• asyncLocalStorage.getStore(): Dette returnerer det Map, der blev givet til asyncLocalStorage.run. Vi bruger det til at gemme og hente request-ID'et. Hvis run ikke er blevet kaldt, vil dette returnere undefined, hvilket er grunden til, at det er vigtigt at kalde run i middlewaren.
• Asynkron Funktion: Funktionen doSomethingAsync simulerer en asynkron operation. Afgørende er, at selvom den er asynkron (ved hjælp af setTimeout), har den stadig adgang til request-ID'et, fordi den kører inden for den kontekst, der er etableret af asyncLocalStorage.run.

Avanceret Brug: Kombination med Logbiblioteker

At integrere AsyncLocalStorage med logbiblioteker (som Winston eller Pino) kan markant forbedre observerbarheden af dine applikationer. Ved at injicere kontekstdata (f.eks. request-ID, bruger-ID) i logbeskeder kan du nemt korrelere logs og spore anmodninger på tværs af forskellige komponenter.

Eksempel med Winston

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modificeret)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Log den indkommende anmodning
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Doing something async...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Handling request...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

I dette eksempel:

• Vi opretter en Winston logger-instans og konfigurerer den til at inkludere request-ID'et fra AsyncLocalStorage i hver logbesked. Den vigtigste del er winston.format.printf, som henter request-ID'et (hvis tilgængeligt) fra AsyncLocalStorage. Vi tjekker, om asyncLocalStorage.getStore() eksisterer for at undgå fejl, når der logges uden for en anmodningskontekst.
• Vi opdaterer middlewaren til at logge den indkommende anmodnings URL.
• Vi opdaterer route-handleren og den asynkrone funktion til at logge beskeder ved hjælp af den konfigurerede logger.

Nu vil alle logbeskeder inkludere request-ID'et, hvilket gør det lettere at spore anmodninger og korrelere logs.

Alternative Tilgange: cls-hooked og Async Hooks

Før AsyncLocalStorage blev tilgængelig, blev biblioteker som cls-hooked almindeligt brugt til asynkron kontekstpropagering. cls-hooked bruger Async Hooks (en lavere-niveau Node.js API) for at opnå lignende funktionalitet. Selvom cls-hooked stadig er meget brugt, foretrækkes AsyncLocalStorage generelt på grund af dens indbyggede natur og forbedrede ydeevne.

Async Hooks (async_hooks)

Async Hooks giver en lavere-niveau API til at spore livscyklussen for asynkrone operationer. Selvom AsyncLocalStorage er bygget oven på Async Hooks, er det ofte mere komplekst og mindre performant at bruge Async Hooks direkte. Async Hooks er mere passende til meget specifikke, avancerede anvendelsestilfælde, hvor finkornet kontrol over den asynkrone livscyklus er påkrævet. Undgå at bruge Async Hooks direkte, medmindre det er absolut nødvendigt.

Hvorfor foretrække AsyncLocalStorage frem for cls-hooked?

• Indbygget: AsyncLocalStorage er en del af Node.js-kernen, hvilket eliminerer behovet for eksterne afhængigheder.
• Ydeevne: AsyncLocalStorage er generelt mere performant end cls-hooked på grund af dens optimerede implementering.
• Vedligeholdelse: Som et indbygget modul vedligeholdes AsyncLocalStorage aktivt af Node.js-kerneteamet.

Overvejelser og Begrænsninger

Selvom AsyncLocalStorage er et kraftfuldt værktøj, er det vigtigt at være opmærksom på dets begrænsninger:

• Kontekstgrænser: AsyncLocalStorage propagerer kun kontekst inden for den samme eksekveringskontekst. Hvis du sender data mellem forskellige processer eller servere (f.eks. via meddelelseskøer eller gRPC), skal du stadig eksplicit serialisere og deserialisere kontekstdataene.
• Hukommelseslækager: Forkert brug af AsyncLocalStorage kan potentielt føre til hukommelseslækager, hvis kontekstdataene ikke bliver ryddet op korrekt. Sørg for, at du bruger asyncLocalStorage.run() korrekt og undgå at gemme store mængder data i AsyncLocalStorage.
• Kompleksitet: Selvom AsyncLocalStorage forenkler kontekstpropagering, kan det også tilføje kompleksitet til din kode, hvis det ikke bruges omhyggeligt. Sørg for, at dit team forstår, hvordan det virker, og følger bedste praksis.
• Ikke en erstatning for globale variabler: AsyncLocalStorage er *ikke* en erstatning for globale variabler. Det er specifikt designet til at propagere kontekst inden for en enkelt anmodning eller transaktion. Overdreven brug kan føre til tæt koblet kode og gøre testning vanskeligere.

Bedste Praksis for Brug af AsyncLocalStorage

For at bruge AsyncLocalStorage effektivt, overvej følgende bedste praksis:

• Brug Middleware: Brug middleware til at initialisere AsyncLocalStorage og gemme kontekstdata i starten af hver anmodning.
• Gem Minimale Data: Gem kun essentielle kontekstdata i AsyncLocalStorage for at minimere hukommelsesforbrug. Undgå at gemme store objekter eller følsomme oplysninger.
• Undgå Direkte Adgang: Indkapsl adgangen til AsyncLocalStorage bag veldefinerede API'er for at undgå tæt kobling og forbedre kodens vedligeholdelighed. Opret hjælpefunktioner eller klasser til at håndtere kontekstdata.
• Overvej Fejlhåndtering: Implementer fejlhåndtering for at håndtere tilfælde, hvor AsyncLocalStorage ikke er korrekt initialiseret.
• Test Grundigt: Skriv enheds- og integrationstests for at sikre, at kontekstpropagering fungerer som forventet.
• Dokumenter Brugen: Dokumenter tydeligt, hvordan AsyncLocalStorage bruges i din applikation for at hjælpe andre udviklere med at forstå kontekstpropageringsmekanismen.

Integration med OpenTelemetry

OpenTelemetry er et open-source observerbarheds-framework, der leverer API'er, SDK'er og værktøjer til at indsamle og eksportere telemetridata (f.eks. traces, metrikker, logs). AsyncLocalStorage kan problemfrit integreres med OpenTelemetry for automatisk at propagere trace-kontekst på tværs af asynkrone operationer.

OpenTelemetry er stærkt afhængig af kontekstpropagering for at korrelere traces på tværs af forskellige services. Ved at bruge AsyncLocalStorage kan du sikre, at trace-konteksten propageres korrekt i din Node.js-applikation, hvilket giver dig mulighed for at bygge et omfattende distribueret sporingssystem.

Mange OpenTelemetry SDK'er bruger automatisk AsyncLocalStorage (eller cls-hooked hvis AsyncLocalStorage ikke er tilgængelig) til kontekstpropagering. Tjek dokumentationen for din valgte OpenTelemetry SDK for specifikke detaljer.

Konklusion

AsyncLocalStorage er et værdifuldt værktøj til håndtering af asynkron kontekstpropagering i server-side JavaScript-applikationer. Ved at bruge det til anmodningssporing, autentificering, logning og andre anvendelsestilfælde kan du bygge mere robuste, observerbare og vedligeholdelsesvenlige applikationer. Selvom alternativer som cls-hooked og Async Hooks eksisterer, er AsyncLocalStorage generelt det foretrukne valg på grund af dens indbyggede natur, ydeevne og brugervenlighed. Husk at følge bedste praksis og være opmærksom på dets begrænsninger for effektivt at udnytte dets kapabiliteter. Evnen til at spore anmodninger og korrelere hændelser på tværs af asynkrone operationer er afgørende for at bygge skalerbare og pålidelige systemer, især i microservices-arkitekturer og komplekse distribuerede miljøer. Brug af AsyncLocalStorage hjælper med at nå dette mål, hvilket i sidste ende fører til bedre debugging, ydeevneovervågning og overordnet applikationssundhed.